home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / time / RCS / ctime.man,v < prev    next >
Encoding:
Text File  |  1991-01-29  |  5.9 KB  |  203 lines
  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.2
  10. date     91.01.28.17.33.41;  author kupfer;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     91.01.28.17.10.55;  author kupfer;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @Man page for ctime, localtime, gmtime, asctime, timezone, tzset, and
  22. mktime.
  23. @
  24.  
  25.  
  26. 1.2
  27. log
  28. @Add description of mktime.
  29. @
  30. text
  31. @.\" Copyright (c) 1980 Regents of the University of California.
  32. .\" All rights reserved.  The Berkeley software License Agreement
  33. .\" specifies the terms and conditions for redistribution.
  34. .\"
  35. .\"    @@(#)ctime.3    6.9 (Berkeley) 9/30/87
  36. .\" $Header$
  37. .\"
  38. .TH CTIME 3  "28 January 1991 (Sprite)"
  39. .SH NAME
  40. ctime, localtime, mktime, gmtime, asctime, timezone, tzset \-  convert date and time to ASCII
  41. .SH SYNOPSIS
  42. .nf
  43. .B void tzset()
  44. .PP
  45. .B char *ctime(clock)
  46. .B time_t *clock;
  47. .PP
  48. .B #include <time.h>
  49. .PP
  50. .B char *asctime(tm)
  51. .B struct tm *tm;
  52. .PP
  53. .B struct tm *localtime(clock)
  54. .B time_t *clock;
  55. .PP
  56. .B time_t mktime(tm)
  57. .B struct tm *tm;
  58. .PP
  59. .B struct tm *gmtime(clock)
  60. .B time_t *clock;
  61. .PP
  62. .B char *timezone(zone, dst)
  63. .fi
  64. .fi
  65. .SH DESCRIPTION
  66. \fITzset\fP uses the value of the environment variable \fBTZ\fP to
  67. set up the time conversion information used by \fIlocaltime\fP.
  68. .PP
  69. If \fBTZ\fP does not appear in the environment, the \fBTZDEFAULT\fP
  70. file (as defined in \fItzfile.h\fP) is used by \fIlocaltime\fP.  If
  71. this file fails for any reason, the GMT offset as provided by the
  72. kernel is used.  In this case, DST is ignored, resulting in the time
  73. being incorrect by some amount if DST is currently in effect.  If
  74. this fails for any reason, GMT is used.
  75. .PP
  76. If \fBTZ\fP appears in the environment but its value is a null string,
  77. Greenwich Mean Time is used; if \fBTZ\fP appears and begins with a
  78. slash, it is used as the absolute pathname of the \fItzfile\fP(5)-format
  79. file from which to read the time conversion information; if \fBTZ\fP
  80. appears and begins with a character other than a slash, it's used as
  81. a pathname relative to the system time conversion information directory,
  82. defined as \fBTZDIR\fP in the include file \fItzfile.h\fP.  If this file
  83. fails for any reason, the GMT offset as provided by the kernel is
  84. used, as described above.  If this fails for any reason, GMT is used.
  85. .PP
  86. Programs that always wish to use local wall clock time should explicitly
  87. remove the environmental variable \fBTZ\fP with \fIunsetenv\fP(3).
  88. .PP
  89. \fICtime\fP converts a long integer, pointed to by \fIclock\fP,
  90. such as returned by \fItime\fP(3), into ASCII and returns a pointer
  91. to a 26-character string in the following form.  All the fields
  92. have constant width.
  93. .PP
  94.     Sun Sep 16 01:03:52 1973\\n\\0
  95. .PP
  96. .I Localtime
  97. and
  98. .I gmtime
  99. return pointers to structures containing
  100. the broken-down time.
  101. .I Localtime
  102. corrects for the time zone and possible daylight savings time;
  103. .I gmtime
  104. converts directly to GMT, which is the time UNIX uses.
  105. .I Mktime
  106. performs the inverse of 
  107. .IR localtime ,
  108. using the year, month, day-of-month, hour, minute, and second to get
  109. the number of seconds since the start of the Epoch.
  110. .I Asctime
  111. converts a broken-down time to ASCII and returns a pointer
  112. to a 26-character string.
  113. .PP
  114. The structure declaration from the include file is:
  115. .PP
  116. .RS
  117. .nf
  118. .nr .0 .8i+\w'int tm_isdst'u
  119. .ta .5i \n(.0u \n(.0u+\w'/* 0-000'u+1n
  120. struct tm {
  121.     int tm_sec;    /* 0-59    seconds */
  122.     int tm_min;    /* 0-59    minutes */
  123.     int tm_hour;    /* 0-23    hour */
  124.     int tm_mday;    /* 1-31    day of month */
  125.     int tm_mon;    /* 0-11    month */
  126.     int tm_year;    /* 0-    year \- 1900 */
  127.     int tm_wday;    /* 0-6    day of week (Sunday = 0) */
  128.     int tm_yday;    /* 0-365    day of year */
  129.     int tm_isdst;    /* flag:    daylight savings time in effect */
  130.     char **tm_zone;    /* abbreviation of timezone name */
  131.     long tm_gmtoff;    /* offset from GMT in seconds */
  132. };
  133. .fi
  134. .RE
  135. .PP
  136. \fITm_isdst\fP is non-zero if a time zone adjustment such as Daylight
  137. Savings time is in effect.
  138. .PP
  139. \fITm_gmtoff\fP is the offset (in seconds) of the time represented
  140. from GMT, with positive values indicating East of Greenwich.
  141. .PP
  142. \fITimezone\fP remains for compatibility reasons only; it's impossible to
  143. reliably map timezone's arguments (\fIzone\fP, a "minutes west of GMT" value
  144. and \fIdst\fP, a "daylight saving time in effect" flag) to a time zone
  145. abbreviation.
  146. .PP
  147. If the environmental string \fITZNAME\fP exists, \fItimezone\fP returns
  148. its value, unless it consists of two comma separated strings, in which
  149. case the second string is returned if \fIdst\fP is non-zero, else
  150. the first string.  If \fITZNAME\fP doesn't exist, \fIzone\fP is checked
  151. for equality with a built-in table of values, in which case \fItimezone\fP
  152. returns the time zone or daylight time zone abbreviation associated with
  153. that value.  If the requested \fIzone\fP does not appear in the table, the
  154. difference from GMT is returned; e.g. in Afghanistan,
  155. \fItimezone(-(60*4+30), 0)\fP is appropriate because it is 4:30 ahead of
  156. GMT, and the string \fBGMT+4:30\fP is returned.  Programs that in the
  157. past used the \fItimezone\fP function should return the zone name as
  158. set by \fIlocaltime\fP to assure correctness.
  159. .SH FILES
  160. .ta \w'/etc/zoneinfo/localtime\0\0'u
  161. /etc/zoneinfo    time zone information directory
  162. .br
  163. /etc/zoneinfo/localtime    local time zone file
  164. .SH SEE ALSO
  165. gettimeofday(2), getenv(3), time(3), tzfile(5), environ(7)
  166. .SH NOTES
  167. The return values point to static data whose content is overwritten by
  168. each call.  This static area is also overwritten by calls to
  169. .IR mktime .
  170. The \fBtm_zone\fP field of a returned \fBstruct tm\fP
  171. points to a static array of characters, which will also be overwritten
  172. at the next call (and by calls to \fItzset\fP).
  173. .PP
  174. This definition of 
  175. .I mktime
  176. is simpler than and slightly incompatible with the BSD version.
  177. @
  178.  
  179.  
  180. 1.1
  181. log
  182. @Initial revision
  183. @
  184. text
  185. @d6 1
  186. d8 1
  187. a8 2
  188. .TH CTIME 3  "September 30, 1987"
  189. .UC 4
  190. d10 1
  191. a10 1
  192. ctime, localtime, gmtime, asctime, timezone, tzset \-  convert date and time to ASCII
  193. d26 3
  194. d75 5
  195. d136 1
  196. a136 1
  197. .SH NOTE
  198. d138 3
  199. a140 1
  200. each call.  The \fBtm_zone\fP field of a returned \fBstruct tm\fP
  201. d143 4
  202. @
  203.